// 版权所有2009 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

package runtime

// 此文件包含Go select语句的实现。

import (
	"internal/abi"
	"runtime/internal/atomic"
	"unsafe"
)

const debugSelect = false

// 选择大小写描述符。
// 编译器已知。
// 此处的更改也必须在src/cmd/compile/internal/walk/select中进行。这是scasetype。
type scase struct {
	c    *hchan         // chan 
	elem unsafe.Pointer // 数据元素
}

var (
	chansendpc = abi.FuncPCABIInternal(chansend)
	chanrecvpc = abi.FuncPCABIInternal(chanrecv)
)

func selectsetpc(pc *uintptr) {
	*pc = getcallerpc()
}

func sellock(scases []scase, lockorder []uint16) {
	var c *hchan
	for _, o := range lockorder {
		c0 := scases[o].c
		if c0 != c {
			c = c0
			lock(&c.lock)
		}
	}
}

func selunlock(scases []scase, lockorder []uint16) {
	// 在解锁
	// 最后一个锁后，我们必须非常小心，不要触摸sel，因为sel可以在最后一个解锁后立即释放。ABCFDG＊＊＊＊＊＊＊＊＊＊
	// 第一个M在运行时调用runtime·park（）。selectgo（）传递sel。
	// 一旦runtime·park（）解锁了最后一个锁，另一个M将使
	// 再次调用select RUNABLE并计划执行的G。
	// 当G在另一个M上运行时，它会锁定所有锁并释放sel。
	// 现在，如果第一个M接触sel，它将访问释放的内存。
	for i := len(lockorder) - 1; i >= 0; i-- {
		c := scases[lockorder[i]].c
		if i > 0 && c == scases[lockorder[i-1]].c {
			continue // 将在下一次迭代中解锁
		}
		unlock(&c.lock)
	}
}

func selparkcommit(gp *g, _ unsafe.Pointer) bool {
	// 有解锁的sudog指向gp的堆栈。Stack 
	// 复制必须锁定那些sudog的通道。
	// 在这里设置activeStackChans，而不是在我们尝试停止
	// 之前，因为我们可能会在
	// 通道锁上的堆栈增长中自锁死。
	gp.activeStackChans = true
	// 标记现在进行堆栈收缩是安全的，
	// 因为任何获取此G的堆栈进行收缩的线程
	// 都保证在此存储之后观察activeStackChans。
	atomic.Store8(&gp.parkingOnChan, 0)
	// 确保我们在设置activeStackChans和
	// 取消驻店后解锁。一旦我们解锁任何
	// 通道锁，gp就有可能被通道操作
	// 准备就绪，因此gp可以在
	// 解锁可见（甚至对gp本身）之前继续运行。

	// 这不能访问gp的堆栈（参见gopark）。在
	// 中，它不能访问*hselect。没关系，
	// 因为当这个被调用时，gp。等待使所有
	// 频道处于锁定状态。
	var lastc *hchan
	for sg := gp.waiting; sg != nil; sg = sg.waitlink {
		if sg.c != lastc && lastc != nil {
			// 一旦我们解锁该频道，
			// 中的字段可能会更改该频道的任何sudog，
			// 包括c和waitlink。由于多个
			// sudogs可能具有相同的通道，因此只有在通过通道的最后一个实例
			// 。
			// 后，我们才能解锁
			unlock(&lastc.lock)
		}
		lastc = sg.c
	}
	if lastc != nil {
		unlock(&lastc.lock)
	}
	return true
}

func block() {
	gopark(nil, nil, waitReasonSelectNoCases, traceEvGoStop, 1) // forever 
}

// selectgo实现select语句。
// 
// cas0指向[NCASE]scase类型的数组，order0指向
// uint16类型的数组，其中NCASE必须小于等于65536。
// 两者都位于goroutine的堆栈上（不管在
// selectgo中是否有任何转义）。
// 
// 对于种族检测器构建，pc0指向
// /[ncases]uintpttr类型的数组（也在堆栈上）；对于其他版本，设置为
// nil。
// 
// selectgo返回所选scase的索引，该索引与相应select{recv，send，default}调用的顺序位置相匹配。
// 此外，如果选择的scase是接收操作，它会报告是否接收到值。
func selectgo(cas0 *scase, order0 *uint16, pc0 *uintptr, nsends, nrecvs int, block bool) (int, bool) {
	if debugSelect {
		print("select: cas0=", cas0, "\n")
	}

	// 注意：为了保持精简的堆栈大小，SCASE 
	// 的数量上限为65536。
	cas1 := (*[1 << 16]scase)(unsafe.Pointer(cas0))
	order1 := (*[1 << 17]uint16)(unsafe.Pointer(order0))

	ncases := nsends + nrecvs
	scases := cas1[:ncases:ncases]
	pollorder := order1[:ncases:ncases]
	lockorder := order1[ncases:][:ncases:ncases]
	// 注意：编译器没有对pollorder/lockorder的底层数组进行零初始化。

	// 即使raceenabled为true，在未使用-race编译的包中也可能会有select 
	// 语句（例如，
	// ensureSigM in runtime/signal_unix.go）。
	var pcs []uintptr
	if raceenabled && pc0 != nil {
		pc1 := (*[1 << 16]uintptr)(unsafe.Pointer(pc0))
		pcs = pc1[:ncases:ncases]
	}
	casePC := func(casi int) uintptr {
		if pcs == nil {
			return 0
		}
		return pcs[casi]
	}

	var t0 int64
	if blockprofilerate > 0 {
		t0 = cputicks()
	}

	// 编译器将静态具有
	// 只有0或1个案例加上默认值的选择重写为更简单的构造。
	// 我们只有这样才能得到这么小的收入。ncase 
	// 这里的值用于一个更大的选择，其中大多数通道
	// 都已为零。通用代码正确地处理了这些
	// 案例，它们非常罕见，不需要进行优化（并且需要测试）。

	// 生成排列顺序
	norder := 0
	for i := range scases {
		cas := &scases[i]

		// 从轮询和锁定顺序中忽略没有通道的案例。
		if cas.c == nil {
			cas.elem = nil // 允许GC 
			continue
		}

		j := fastrandn(uint32(norder + 1))
		pollorder[norder] = pollorder[j]
		pollorder[j] = uint16(i)
		norder++
	}
	pollorder = pollorder[:norder]
	lockorder = lockorder[:norder]

	// 按Hchan地址对案例进行排序，以获得锁定顺序。
	// 简单的堆排序，保证n log n时间和恒定的堆栈占用空间。
	for i := range lockorder {
		j := i
		// 从pollorder开始，在同一频道上排列案例。
		c := scases[pollorder[i]].c
		for j > 0 && scases[lockorder[(j-1)/2]].c.sortkey() < c.sortkey() {
			k := (j - 1) / 2
			lockorder[j] = lockorder[k]
			j = k
		}
		lockorder[j] = pollorder[i]
	}
	for i := len(lockorder) - 1; i >= 0; i-- {
		o := lockorder[i]
		c := scases[o].c
		lockorder[i] = lockorder[0]
		j := 0
		for {
			k := j*2 + 1
			if k >= i {
				break
			}
			if k+1 < i && scases[lockorder[k]].c.sortkey() < scases[lockorder[k+1]].c.sortkey() {
				k++
			}
			if c.sortkey() < scases[lockorder[k]].c.sortkey() {
				lockorder[j] = lockorder[k]
				j = k
				continue
			}
			break
		}
		lockorder[j] = o
	}

	if debugSelect {
		for i := 0; i+1 < len(lockorder); i++ {
			if scases[lockorder[i]].c.sortkey() > scases[lockorder[i+1]].c.sortkey() {
				print("i=", i, " x=", lockorder[i], " y=", lockorder[i+1], "\n")
				throw("select: broken sort")
			}
		}
	}

	// 锁定选择中涉及的所有通道
	sellock(scases, lockorder)

	var (
		gp     *g
		sg     *sudog
		c      *hchan
		k      *scase
		sglist *sudog
		sgnext *sudog
		qp     unsafe.Pointer
		nextp  **sudog
	)

	// 通过1-查找已在等待的内容
	var casi int
	var cas *scase
	var caseSuccess bool
	var caseReleaseTime int64 = -1
	var recvOK bool
	for _, casei := range pollorder {
		casi = int(casei)
		cas = &scases[casi]
		c = cas.c

		if casi >= nsends {
			sg = c.sendq.dequeue()
			if sg != nil {
				goto recv
			}
			if c.qcount > 0 {
				goto bufrecv
			}
			if c.closed != 0 {
				goto rclose
			}
		} else {
			if raceenabled {
				racereadpc(c.raceaddr(), casePC(casi), chansendpc)
			}
			if c.closed != 0 {
				goto sclose
			}
			sg = c.recvq.dequeue()
			if sg != nil {
				goto send
			}
			if c.qcount < c.dataqsiz {
				goto bufsend
			}
		}
	}

	if !block {
		selunlock(scases, lockorder)
		casi = -1
		goto retc
	}

	// 通过2-在所有通道上排队
	gp = getg()
	if gp.waiting != nil {
		throw("gp.waiting != nil")
	}
	nextp = &gp.waiting
	for _, casei := range lockorder {
		casi = int(casei)
		cas = &scases[casi]
		c = cas.c
		sg := acquireSudog()
		sg.g = gp
		sg.isSelect = true
		// 在分配elem和在gp上排队
		// sg之间没有堆栈拆分。在copystack可以找到的地方等待。
		sg.elem = cas.elem
		sg.releasetime = 0
		if t0 != 0 {
			sg.releasetime = -1
		}
		sg.c = c
		// 按锁定顺序构建等待列表。
		*nextp = sg
		nextp = &sg.waitlink

		if casi < nsends {
			c.sendq.enqueue(sg)
		} else {
			c.recvq.enqueue(sg)
		}
	}

	// 等待有人叫醒我们
	gp.param = nil
	// 向任何试图缩小我们的堆栈的人发出信号，我们即将
	// 停在频道上。此G的状态
	// 更改与我们设置gp之间的窗口。activeStackChans对
	// 堆栈收缩不安全。
	atomic.Store8(&gp.parkingOnChan, 1)
	gopark(selparkcommit, nil, waitReasonSelect, traceEvGoBlockSelect, 1)
	gp.activeStackChans = false

	sellock(scases, lockorder)

	gp.selectDone = 0
	sg = (*sudog)(gp.param)
	gp.param = nil

	// 通过3-从失败的通道中退出
	// 否则它们会堆积在安静的通道上
	// 记录成功的案例（如果有）。
	// 我们单独把这些运动狗锁起来。
	casi = -1
	cas = nil
	caseSuccess = false
	sglist = gp.waiting
	// 在与gp断开链接之前，请清除所有元素。等待。
	for sg1 := gp.waiting; sg1 != nil; sg1 = sg1.waitlink {
		sg1.isSelect = false
		sg1.elem = nil
		sg1.c = nil
	}
	gp.waiting = nil

	for _, casei := range lockorder {
		k = &scases[casei]
		if sg == sglist {
			// sg已经被叫醒我们的G排了队。
			casi = int(casei)
			cas = k
			caseSuccess = sglist.success
			if sglist.releasetime > 0 {
				caseReleaseTime = sglist.releasetime
			}
		} else {
			c = k.c
			if int(casei) < nsends {
				c.sendq.dequeueSudoG(sglist)
			} else {
				c.recvq.dequeueSudoG(sglist)
			}
		}
		sgnext = sglist.waitlink
		sglist.waitlink = nil
		releaseSudog(sglist)
		sglist = sgnext
	}

	if cas == nil {
		throw("selectgo: bad wakeup")
	}

	c = cas.c

	if debugSelect {
		print("wait-return: cas0=", cas0, " c=", c, " cas=", cas, " send=", casi < nsends, "\n")
	}

	if casi < nsends {
		if !caseSuccess {
			goto sclose
		}
	} else {
		recvOK = caseSuccess
	}

	if raceenabled {
		if casi < nsends {
			raceReadObjectPC(c.elemtype, cas.elem, casePC(casi), chansendpc)
		} else if cas.elem != nil {
			raceWriteObjectPC(c.elemtype, cas.elem, casePC(casi), chanrecvpc)
		}
	}
	if msanenabled {
		if casi < nsends {
			msanread(cas.elem, c.elemtype.size)
		} else if cas.elem != nil {
			msanwrite(cas.elem, c.elemtype.size)
		}
	}
	if asanenabled {
		if casi < nsends {
			asanread(cas.elem, c.elemtype.size)
		} else if cas.elem != nil {
			asanwrite(cas.elem, c.elemtype.size)
		}
	}

	selunlock(scases, lockorder)
	goto retc

bufrecv:
	// 可以从缓冲区接收
	if raceenabled {
		if cas.elem != nil {
			raceWriteObjectPC(c.elemtype, cas.elem, casePC(casi), chanrecvpc)
		}
		racenotify(c, c.recvx, nil)
	}
	if msanenabled && cas.elem != nil {
		msanwrite(cas.elem, c.elemtype.size)
	}
	if asanenabled && cas.elem != nil {
		asanwrite(cas.elem, c.elemtype.size)
	}
	recvOK = true
	qp = chanbuf(c, c.recvx)
	if cas.elem != nil {
		typedmemmove(c.elemtype, cas.elem, qp)
	}
	typedmemclr(c.elemtype, qp)
	c.recvx++
	if c.recvx == c.dataqsiz {
		c.recvx = 0
	}
	c.qcount--
	selunlock(scases, lockorder)
	goto retc

bufsend:
	// 可以发送到缓冲区
	if raceenabled {
		racenotify(c, c.sendx, nil)
		raceReadObjectPC(c.elemtype, cas.elem, casePC(casi), chansendpc)
	}
	if msanenabled {
		msanread(cas.elem, c.elemtype.size)
	}
	if asanenabled {
		asanread(cas.elem, c.elemtype.size)
	}
	typedmemmove(c.elemtype, chanbuf(c, c.sendx), cas.elem)
	c.sendx++
	if c.sendx == c.dataqsiz {
		c.sendx = 0
	}
	c.qcount++
	selunlock(scases, lockorder)
	goto retc

recv:
	// 可以从休眠发送器（sg）
	recv(c, sg, cas.elem, func() { selunlock(scases, lockorder) }, 2)
	if debugSelect {
		print("syncrecv: cas0=", cas0, " c=", c, "\n")
	}
	recvOK = true
	goto retc

rclose:
	// 在封闭通道末尾读取
	selunlock(scases, lockorder)
	recvOK = false
	if cas.elem != nil {
		typedmemclr(c.elemtype, cas.elem)
	}
	if raceenabled {
		raceacquire(c.raceaddr())
	}
	goto retc

send:
	// 可以发送到休眠接收器（sg）
	if raceenabled {
		raceReadObjectPC(c.elemtype, cas.elem, casePC(casi), chansendpc)
	}
	if msanenabled {
		msanread(cas.elem, c.elemtype.size)
	}
	if asanenabled {
		asanread(cas.elem, c.elemtype.size)
	}
	send(c, sg, cas.elem, func() { selunlock(scases, lockorder) }, 2)
	if debugSelect {
		print("syncsend: cas0=", cas0, " c=", c, "\n")
	}
	goto retc

retc:
	if caseReleaseTime > 0 {
		blockevent(caseReleaseTime-t0, 1)
	}
	return casi, recvOK

sclose:
	// 在封闭通道发送
	selunlock(scases, lockorder)
	panic(plainError("send on closed channel"))
}

func (c *hchan) sortkey() uintptr {
	return uintptr(unsafe.Pointer(c))
}

// runtimeSelect是传递给rselect的单个大小写。
// 这必须匹配/反映/价值。go:/runtimeSelect 
type runtimeSelect struct {
	dir selectDir
	typ unsafe.Pointer // 通道类型（此处不使用）
	ch  *hchan         // 通道
	val unsafe.Pointer // ptr to data（SendDir）或ptr to RecvDir（接收缓冲区）
}

// 这些值必须匹配/反映/价值。开始：/SelectDir。
type selectDir int

const (
	_             selectDir = iota
	selectSend              // case Chan<-发送
	selectRecv              // case<-Chan:
	selectDefault           // 默认
)

// go:linkname reflect_rselect reflect。r选择
func reflect_rselect(cases []runtimeSelect) (int, bool) {
	if len(cases) == 0 {
		block()
	}
	sel := make([]scase, len(cases))
	orig := make([]int, len(cases))
	nsends, nrecvs := 0, 0
	dflt := -1
	for i, rc := range cases {
		var j int
		switch rc.dir {
		case selectDefault:
			dflt = i
			continue
		case selectSend:
			j = nsends
			nsends++
		case selectRecv:
			nrecvs++
			j = len(cases) - nrecvs
		}

		sel[j] = scase{c: rc.ch, elem: rc.val}
		orig[j] = i
	}

	// 仅为默认情况。
	if nsends+nrecvs == 0 {
		return dflt, false
	}

	// 如有必要，压缩sel和orig。
	if nsends+nrecvs < len(cases) {
		copy(sel[nsends:], sel[len(cases)-nrecvs:])
		copy(orig[nsends:], orig[len(cases)-nrecvs:])
	}

	order := make([]uint16, 2*(nsends+nrecvs))
	var pc0 *uintptr
	if raceenabled {
		pcs := make([]uintptr, nsends+nrecvs)
		for i := range pcs {
			selectsetpc(&pcs[i])
		}
		pc0 = &pcs[0]
	}

	chosen, recvOK := selectgo(&sel[0], &order[0], pc0, nsends, nrecvs, dflt == -1)

	// 将所选内容翻译回来电者的订单。
	if chosen < 0 {
		chosen = dflt
	} else {
		chosen = orig[chosen]
	}
	return chosen, recvOK
}

func (q *waitq) dequeueSudoG(sgp *sudog) {
	x := sgp.prev
	y := sgp.next
	if x != nil {
		if y != nil {
			// 队列中间
			x.next = y
			y.prev = x
			sgp.next = nil
			sgp.prev = nil
			return
		}
		// 队列结束
		x.next = nil
		q.last = x
		sgp.prev = nil
		return
	}
	if y != nil {
		// 队列开始
		y.prev = nil
		q.first = y
		sgp.next = nil
		return
	}

	// x==y==nil。sgp是队列中唯一的元素
	// 或者它已被删除。使用q.first来消除歧义。
	if q.first == sgp {
		q.first = nil
		q.last = nil
	}
}
